% -*- Mode: LaTeX; Package: CLIM-USER -*-

\chapter {Command Processing}
\label {command-processor}

\section {Commands}

A \concept{command} is an object that represents a user interaction.  Commands
are stored as a cons of the command name and a list of the command's arguments.
All positional arguments will be represented in the command object, but only
those keywords arguments that were explicitly supplied by the user will be
included.  When the first element of the cons is \cl{apply}'ed to the rest of
the cons, the code representing that interaction is executed.

A \concept{partial command} is a command object with the value of
\cl{*unsupplied-argument-marker*} in place of any argument that needs to be
filled in.

Every command is named by \concept{command name}, which is a symbol.  To avoid
collisions among command names, application frames should reside in their own
package; for example, the \cl{com-show-chart} command might be defined for both
a spreadsheet and a medical application.

\Defun {command-name} {command}

Given a command object \arg{command}, returns the command name.

\Defun {command-arguments} {command}

Given a command object \arg{command}, returns the command's arguments.

\Defun {partial-command-p} {command}

Returns \term{true} if the \arg{command} is a partial command, that is, has any
occurrences of \cl{*unsupplied-argument-marker*} in it.  Otherwise,
\cl{partial-command-p} returns \term{false}.


\def\DefineFrameCommand{\cl{define-{\it frame}-command}}


\Defmacro {define-command} {name-and-options arguments \body body}

This is the most basic command-defining form.  Usually, the programmer will not
use \cl{define-command} directly, but will instead use a \DefineFrameCommand\
form that is automatically generated by \cl{define-application-frame}.
\DefineFrameCommand\  adds the command to the application frame's command table.
By default, \cl{define-command} does not add the command to any command table.

\arg{name-and-options} is either a command name, or a cons of the command name
and a list of keyword-value pairs.

\cl{define-command} defines two functions.  The first function has the same name
as the command name, and implements the body of the command.  It takes as
arguments the arguments to the command as specified by the \cl{define-command}
form, as required and keyword arguments.

The name of the other function defined by \cl{define-command} is unspecified.
It implements the code used by the command processor for parsing and returning
the command's arguments.

The keywords from \arg{name-and-options} can be:

\begin{itemize}
\item \cl{:command-table} \arg{command-table-name}, where
\arg{command-table-name} either names a command table to which the command will
be added, or is \cl{nil} (the default) to indicate that the command should not
be added to any command table.  If the command table does not exist, the
\cl{command-table-not-found} error will be signalled.  This keyword is only
accepted by \cl{define-command}, not by \DefineFrameCommand.

\item \cl{:name} \arg{string}, where \arg{string} is a string that will be used
as the command-line name for the command for keyboard interactions in the
command table specified by the \cl{:command-table} option.  The default is
\cl{nil}, meaning that the command will not be available via command-line
interactions.  If \arg{string} is \cl{t}, then the command-line name will be
generated automatically, as described in \cl{add-command-to-command-table}.

\item \cl{:menu} \arg{menu-spec}, where \arg{menu-spec} describes an item in the
menu of the command table specified by the \cl{:command-table} option.  The
default is \cl{nil}, meaning that the command will not be available via menu
interactions.  If \arg{menu-spec} is a string, then that string will be used as
the menu name.  If \arg{menu-spec} is \cl{t}, then if a command-line name was
supplied, it will be used as the menu name; otherwise the menu name will be
generated automatically, as described in \cl{add-command-to-command-table}.
Otherwise, \arg{menu-spec} must be a cons of the form \cl{(\arg{string} .
\arg{menu-options})}, where \arg{string} is the menu name and \arg{menu-options}
consists of keyword-value pairs.  The valid keywords are \cl{:after},
\cl{:documentation}, and \cl{:text-style}, which are interpreted as for
\cl{add-menu-item-to-command-table}.

\item \cl{:keystroke} \arg{gesture}, where \arg{gesture} is a keyboard gesture
name that specifies a keystroke accelerator to use for this command in the
command table specified by the \cl{:command-table} option.  The default is
\cl{nil}, meaning that there is no keystroke accelerator.
\end{itemize}

The \cl{:name}, \cl{:menu}, and \cl{:keystroke} options are only allowed if
the \cl{:command-table} option was supplied explicitly or implicitly, as in
\DefineFrameCommand.

\arg{arguments} is a list consisting of argument descriptions.  A single occurrence of
the symbol \cl{\key} may appear in \arg{arguments} to separate required command arguments
from keyword arguments.  Each argument description consists of a parameter
variable, followed by a presentation type specifier, followed by keyword-value
pairs.  The keywords can be:

\begin{itemize}
\item \cl{:default} \arg{value}, where \arg{value} is the default that should
be used for the argument, as for \cl{accept}.

\item \cl{:default-type} is the same as for \cl{accept}.

\item \cl{:display-default} is the same as for \cl{accept}.

\item \cl{:mentioned-default} \arg{value}, where \arg{value} is the default
that should be used for the argument when a keyword is explicitly supplied via
the command-line processor, but no value is supplied for it.
\cl{:mentioned-default} is only allowed on keyword arguments.

\item \cl{:prompt} \arg{string}, where \arg{string} is a prompt to print out
during command-line parsing, as for \cl{accept}.

\item \cl{:documentation} \arg{string}, where \arg{string} is a documentation
string that describes what the argument is.

\item \cl{:when} \arg{form}.  \arg{form} is evaluated in a scope where the
parameter variables for the required parameters are bound, and if the result is
\cl{nil}, the keyword argument is not available.  \cl{:when} is only allowed on
keyword arguments, and \arg{form} cannot use the values of other keyword
arguments.

\item \cl{:gesture} \arg{gesture}, where \arg{gesture} is either a pointer
gesture name or a list of a pointer gesture name followed by keyword-value
pairs.  When a gesture is supplied, a presentation translator will be defined
that translates from this argument's presentation type to an instance of this
command with the selected object as the argument; the other arguments will be
filled in with their default values.  The keyword-value pairs are used as
options for the translator.  Valid keywords are \cl{:tester}, \cl{:menu},
\cl{:priority}, \cl{:echo}, \cl{:documentation}, and
\cl{:pointer-documentation}.  The default for \arg{gesture} is \cl{nil}, meaning
no translator will be written.  \cl{:gesture} is only allowed when the
\cl{:command-table} option was supplied to the command-defining form.
\end{itemize}

\arg{body} implements the body of the command.  It has lexical access to all of
the commands arguments.  If the body of the command needs access to the
application frame itself, it should use \cl{*application-frame*}.  The returned
values of body are ignored.  \arg{body} may have zero or more declarations as
its first forms.

\cl{define-command} must arrange for the function that implements the body of
the command to get the proper values for unsupplied keyword arguments.

\arg{name-and-options} and \arg{body} are not evaluated.  In the argument
descriptions, the parameter variable name is not evaluated, and everything else
is evaluated at run-time when argument parsing reaches that argument, except
that the value for \cl{:when} is evaluated when parsing reaches the keyword
arguments, and \cl{:gesture} isn't evaluated at all.


\section {Command Tables}

There are four main styles of interaction: keyboard interaction using a command-
line processor, keyboard interaction using keystroke accelerators, mouse
interaction via command menus, and mouse interaction via translators.  A
\concept{command table} is an object that serves to mediate between an
application frame, a set of commands, and the four interaction styles.  Command
tables contain the following information:

\begin{itemize}
\item The name of the command table, which is a symbol.

\item An ordered list of command tables to inherit from.

\item The set of commands that are present in this command table.

\item A table that associates command-line names to command names (used to
support command-line processor interactions).

\item A set of presentation translators, defined via
\cl{define-presentation-translator} and
\cl{define-presentation-to-command-translator}.

\item A table that associates keyboard gesture names to menu items (used to
support keystroke accelerator interactions).  By default, the keystroke
accelerator table does not contain any items inherited from superior command
tables, although this can be overridden by supplying \cl{t} or
\cl{:keystrokes} as the value of the \cl{:inherit-menu} option to
\cl{define-command-table}.

\item A menu that associates menu names to command menu items (used to support
interaction via command menus).  The command menu items can invoke commands
or sub-menus.  By default, the menu does not contain any command menu items
inherited from superior command tables, although this can be overridden by
supplying \cl{t} or \cl{:menu} as the \cl{:inherit-menu} option to
\cl{define-command-table}.
\end{itemize}

We say that a command is \concept{present} in a command table when it has been
added to that command table.  We say that a command is \concept{accessible} in a
command table when it is present in that command table or is present in any of
the command tables from which that command table inherits.


\Defprotoclass {command-table}

The protocol class that corresponds to command tables.
\IfYouWantClass {a} {command table} {command-table}
\Mutable

\Defpredicate {command-table-p} {object}

Returns \term{true} if \arg{object} is a \term{command table}, otherwise returns
\term{false}.

\Defclass {standard-command-table}

The instantiable class that implements command tables, a subclass of
\cl{command-table}.  \cl{make-command-table} returns objects that are members of
this class.

\issue {SWM} {Do we really want to advertise these classes, since all the
functions below are vanilla functions instead of generic functions?  Or should
we make those functions be generic functions?}


\Defgeneric {command-table-name} {command-table}

Returns the name of the \term{command table} \arg{command-table}.

\Defgeneric {command-table-inherit-from} {command-table}

Returns a list of the command tables from which the \term{command table}
\arg{command-table} inherits.
\ReadOnly


\Defmacro {define-command-table} {name \key inherit-from menu inherit-menu}

Defines a command table whose name is the symbol \arg{name}.  The new command
table inherits from all of the command tables specified by \arg{inherit-from},
which is a list of \concept{command table designators} (that is, either a command
table or a symbol that names a command table).  The inheritance is done by union
with shadowing.  If no inheritance is specified, the command table will be made
to inherit from CLIM's global command table.  (This command table contains such
things as the ``menu'' translator that is associated with the right-hand button
on pointers.)

If \arg{inherit-menu} is \cl{t}, the new command table will inherit the menu
items and keystroke accelerators from all of the inherited command tables.  If
it is \term{nil} (the default), no menu items or keystroke accelerators will
be inherited. If it is \cl{:menu}, only menu items will be inherited. If it is
\cl{:keystrokes}, only keystroke accelerators will be inherited.

\arg{menu} can be used to specify a menu for the command table.  The value of
\arg{menu} is a list of clauses.  Each clause is a list with the syntax
\cl{(\arg{string} \arg{type} \arg{value} \key \arg{keystroke}
\arg{documentation} \arg{text-style})}, where \arg{string}, \arg{type},
\arg{value}, \arg{keystroke}, \arg{documentation}, and \arg{text-style} are as
for \cl{add-menu-item-to-command-table}.

If the command table named by \arg{name} already exists,
\cl{define-command-table} will modify the existing command table to have the new
value for \arg{inherit-from} and \arg{menu}, and leaves the other attributes for
the existing command table alone.

None of \cl{define-command-table}'s arguments are evaluated.


\Defun {make-command-table} {name \key inherit-from menu inherit-menu (errorp t)}

Creates a command table named \arg{name}.  \arg{inherit-from}, \arg{menu}, and
\arg{inherit-menu} are the same as for \cl{define-command-table}.
\cl{make-command-table} does not implicitly include CLIM's global command table
in the inheritance list for the new command table.  If the command table already
exists and \arg{errorp} is \term{true}, the \cl{command-table-already-exists}
error will be signalled.  If the command table already exists and \arg{errorp}
is \term{false}, then the old command table will be discarded.  The returned
value is the command table.


\Defun {find-command-table} {name \key (errorp t)}

Returns the command table named by \arg{name}.  If \arg{name} is itself a
command table, it is returned.  If the command table is not found and
\arg{errorp} is \term{true}, the \cl{command-table-not-found} error will be
signalled.


\Deferror {command-table-error}

The class that is the superclass of the following four conditions.  This class
is a subclass of \cl{error}.

\cl{command-table-error} and its subclasses must handle the \cl{:format-string}
and \cl{:format-arguments} initargs, which are used to specify a control string
and arguments for a call to \cl{format}.

\Deferror {command-table-not-found}

The error that is signalled by such functions as \cl{find-command-table} when a
command table is not found.

\Deferror {command-table-already-exists}

The error that is signalled when the programmer tries to create a command table
that already exists.

\Deferror {command-not-present}

The error that is signalled when a command is not present in a command table.

\Deferror {command-not-accessible}

The error that is signalled when a command is not accessible in a command table.

\Deferror {command-already-present}

The error that is signalled when a function tries to add a command to a command
table when it is already present in the command table.


\Defun {add-command-to-command-table} {command-name command-table
                                       \key name menu keystroke (errorp t)}

Adds the command named by \arg{command-name} to the command table specified by
the \term{command table designator} \arg{command-table}.

\arg{name} is the command-line name for the command, and can be \cl{nil},
\cl{t}, or a string.  When it is \cl{nil}, the command will not be available via
command-line interactions.  When it is a string, that string is the command-line
name for the command.  When it is \cl{t}, the command-line name is generated
automatically by calling \cl{command-name-from-symbol} on \arg{command-name}.
For the purposes of command-line name lookup, the character case of \arg{name}
is ignored.

\arg{menu} is a menu item for the command, and can be \cl{nil}, \cl{t}, a
string, or a cons.  When it is \cl{nil}, the command will not be available via
menus.  When it is a string, the string will be used as the menu name.  When
\arg{menu} is \cl{t} and \arg{name} is a string, then \arg{name} will be used
as the menu name.  When \arg{menu} is \cl{t} and \arg{name} is not a string,
an automatically generated menu name will be used.  When \arg{menu} is a cons
of the form \cl{(\arg{string} . \arg{menu-options})}, \arg{string} is the menu
name and \arg{menu-options} consists of keyword-value pairs.  The valid
keywords are \cl{:after}, \cl{:documentation}, and \cl{:text-style}, which are
interpreted as for \cl{add-menu-item-to-command-table}.

The value for \arg{keystroke} is either keyboard gesture name or \cl{nil}.  When
it is a gesture name, it is the keystroke accelerator for the command; otherwise
the command will not be available via keystroke accelerators.

If the command is already present in the command table and \arg{errorp} is
\term{true}, the \cl{command-already-present} error will be signalled.  When the
command is already present in the command table and \arg{errorp} is
\term{false}, then the old command-line name, menu, and keystroke accelerator
will first be removed from the command table.


\Defun {remove-command-from-command-table} {command-name command-table \key (errorp t)}

Removes the command named by \arg{command-name} from the command table specified
by the \term{command table designator} \arg{command-table}.

If the command is not present in the command table and \arg{errorp} is
\term{true}, the \cl{command-not-present} error will be signalled.

\Defun {command-name-from-symbol} {symbol}

Generates a string suitable for use as a command-line name from the symbol
\arg{symbol}.  The string consists the symbol name with the hyphens replaced by
spaces, and the words capitalized.  If the symbol name is prefixed by ``COM-'',
the prefix is removed.  For example, if the symbol is \cl{com-show-file}, the
result string will be ``Show File''.


\Defmacro {do-command-table-inheritance}  {(command-table-var command-table) \body body}

Successively executes \arg{body} with \arg{command-table-var} bound first to
the command table specified by the \term{command table designator}
\arg{command-table}, and then (recursively) to all of the command tables from
which \arg{command-table} inherits.

The \arg{command-table-var} argument is not evaluated.  \arg{body} may have zero
or more declarations as its first forms.

\Defun {map-over-command-table-commands} {function command-table \key (inherited t)}

Applies \arg{function} to all of the commands accessible in the command table
specified by the \term{command table designator} \arg{command-table}.
\arg{function} must be a function that takes a single argument, the command
name; it has dynamic extent.

If \arg{inherited} is \term{false}, this applies \arg{function} only to
those commands present in \arg{command-table}, that is, it does not map over
any inherited command tables.  If \arg{inherited} is \term{true}, then the
inherited command tables are traversed in the same order as for
\cl{do-command-table-inheritance}.

\Defun {map-over-command-table-names} {function command-table \key (inherited t)}

Applies \arg{function} to all of the command-line name accessible in the
command table specified by the \term{command table designator}
\arg{command-table}.  \arg{function} must be a function of two arguments,
the command-line name and the command name; it has dynamic extent.

If \arg{inherited} is \term{false}, this applies \arg{function} only to
those command-line names present in \arg{command-table}, that is, it does
not map over any inherited command tables.  If \arg{inherited} is
\term{true}, then the inherited command tables are traversed in the same
order as for \cl{do-command-table-inheritance}.


\Defun {command-present-in-command-table-p} {command-name command-table}

Returns \term{true} if the command named by \arg{command-name} is present in
the command table specified by the \term{command table designator}
\arg{command-table}, otherwise returns \term{false}.

\Defun {command-accessible-in-command-table-p} {command-name command-table}

If the command named by \arg{command-name} is not accessible in the command
table specified by the \term{command table designator} \arg{command-table}, then
this function returns \cl{nil}.  Otherwise, it returns the command table in
which the command was found.


\Defun {find-command-from-command-line-name} {name command-table \key (errorp t)}

Given a command-line name \arg{name} and a command table, returns two values,
the command name and the command table in which the command was found.  If the
command is not accessible in \arg{command-table} and \arg{errorp} is
\term{true}, the \cl{command-not-accessible} error will be signalled.
\arg{command-table} is a \term{command table designator}.

\cl{find-command-from-command-line-name} ignores character case.

\Defun {command-line-name-for-command} {command-name command-table \key (errorp t)}

Returns the command-line name for \arg{command-name} as it is installed in
\arg{command-table}.  \arg{command-table} is a \term{command table designator}.

If the command is not accessible in \arg{command-table} or has no command-line
name, then there are three possible results.  If \arg{errorp} is \cl{nil}, then
the returned value will be \cl{nil}.  If \arg{errorp} is \cl{:create}, then a
command-line name will be generated, as described in
\cl{add-command-to-command-table}.  Otherwise, if \arg{errorp} is \cl{t}, then
the \cl{command-not-accessible} error will be signalled.  The returned
command-line name should not be modified.

This is the inverse of \cl{find-command-from-command-line-name}.  It should be
implemented in such as way that it is fast, since it may be used by presentation
translators to produce pointer documentation.

\Defun {command-table-complete-input} {command-table string action \key frame}

A function that can be used as in conjunction with \cl{complete-input} in order
to complete over all of the command lines names accessible in the \term{command
table} \arg{command-table}.  \arg{string} is the input string to complete over,
and \arg{action} is as for \cl{complete-from-possibilities}.

\arg{frame} is either an application frame, or \cl{nil}.  If \arg{frame} is
supplied, no disabled commands should be offered as valid completions.

\cl{command-table-complete-input} could be implemented by collecting all of the
command line names accessible in the command table and then calling
\cl{complete-from-possibilities}, or it could be implemented more efficiently
than that (such as by caching a sorted list of command line names and using a
binary search).


\Defcommandtable {global-command-table}

The command table from which all other command tables inherit by default.
Programmers should not explicitly add anything to or remove anything from this
command table.  CLIM can use this command to store internals or system-wide
commands and translators (for example, the translator that implements the
``identity'' translation from a type to itself).  Programmers should not
casually install any commands or translators into this command table.

\Defcommandtable {user-command-table}

A command table that can be used by the programmer for any purpose.  CLIM does
not use it for anything, and its contents are completely undefined.


\section {Command Menus}

Each command table may have a menu consisting of an ordered sequence of command
menu items.  The menu specifies a mapping from a menu name (the name displayed
in the menu) to a command menu item.  The menu of an application frame's
top-level command table may be presented in a window system specific way, for
example, as a menu bar.

Command menu items are stored as a list of the form
\cl{(\arg{type} \arg{value} . \arg{options})}, where \arg{type} and \arg{value}
are as in \cl{add-menu-item-to-command-table}, and \arg{options} is a list of
keyword-value pairs.  The allowable keywords are \cl{:documentation}, which is
used to supply optional pointer documentation for the command menu item, and
\cl{:text-style}, which is used to indicate what text style should be used for
this command menu item when it is displayed in a command menu.

\cl{add-menu-item-to-command-table}, \cl{remove-menu-item-from-command-table},
and \cl{find-menu-item} ignore the character case of the command menu item's
name when searching through the command table's menu.


\Defun {add-menu-item-to-command-table} {command-table string type value
                                         \key documentation (after ':end) keystroke
                                              text-style (errorp t)}

Adds a command menu item to \arg{command-table}'s menu.  \arg{string} is the
name of the command menu item; its character case is ignored.  \arg{type} is
either \cl{:command}, \cl{:function}, \cl{:menu}, or \cl{:divider}.
\arg{command-table} is a \term{command table designator}.

\issue {SWM} {How do we make iconic command menus?  Probably another keyword...}

When \arg{type} is \cl{:command}, \arg{value} must be a command (a cons of a
command name followed by a list of the command's arguments), or a command name.
(When \arg{value} is a command name, it behaves as though a command with no
arguments was supplied.)  In the case where all of the command's required
arguments are supplied, clicking on an item in the menu invokes the command
immediately.  Otherwise, the user will be prompted for the remaining required
arguments.

When \arg{type} is \cl{:function}, \arg{value} must be function having
indefinite extent that, when called, returns a command.  The function is called
with two arguments, the gesture the user used to select the item (either a
keyboard or button press event) and a ``numeric argument''.

When \arg{type} is \cl{:menu}, this item indicates that a sub-menu will be
invoked, and so \arg{value} must be another command table or the name of
another command table.

When \arg{type} is \cl{:divider}, some sort of a dividing line is displayed in
the menu at that point.  If \arg{string} is supplied, it will be drawn as the
divider instead of a line.  If the look and feel provided by the underlying
window system has no corresponding concept, \cl{:divider} items may be ignored.
\arg{value} is ignored.

\arg{documentation} is a documentation string, which can be used as mouse
documentation for the command menu item.

\arg{text-style} is either a text style spec or \cl{nil}.  It is used to
indicate that the command menu item should be drawn with the supplied text style
in command menus.

\arg{after} must be either \cl{:start} (meaning to add the new item to the
beginning of the menu), \cl{:end} or \cl{nil} (meaning to add the new item to
the end of the menu), or a string naming an existing entry (meaning to add the
new item after that entry).  If \arg{after} is \cl{:sort}, then the item is
inserted in such as way as to maintain the menu in alphabetical order.

If \arg{keystroke} is supplied, the item will be added to the command table's
keystroke accelerator table.  The value of \arg{keystroke} must be a keyboard
gesture name.  This is exactly equivalent to calling
\cl{add-keystroke-to-command-table} with the arguments \arg{command-table},
\arg{keystroke}, \arg{type} and \arg{value}.  When \arg{keystroke} is supplied
and \arg{type} is \cl{:command} or \cl{:function}, typing a key on the keyboard
that matches to the keystroke accelerator gesture will invoke the command
specified by \arg{value}.  When \arg{type} is \cl{:menu}, the command will
continue to be read from the sub-menu indicated by \arg{value} in a window
system specific manner.

If the item named by \arg{string} is already present in the command table's menu
and \arg{errorp} is \term{true}, then the \cl{command-already-present} error
will be signalled.  When the item is already present in the command table's menu
and \arg{errorp} is \term{false}, the old item will first be removed from the
menu.  Note that the character case of \arg{string} is ignored when searching
the command table's menu.


\Defun {remove-menu-item-from-command-table} {command-table string \key (errorp t)}

Removes the item named by \arg{string} from \arg{command-table}'s menu.
\arg{command-table} is a \term{command table designator}.

If the item is not present in the command table's menu and \arg{errorp} is
\term{true}, then the \cl{command-not-present} error will be signalled.  Note
that the character case of \arg{string} is ignored when searching the command
table's menu.


\Defun {map-over-command-table-menu-items} {function command-table \key (inherited t)}

Applies \arg{function} to all of the items in \arg{command-table}'s menu.
\arg{function} must be a function of three arguments, the menu name, the
keystroke accelerator gesture (which will be \cl{nil} if there is none), and the
command menu item; it has dynamic extent.  The command menu items are mapped
over in the order specified by \cl{add-menu-item-to-command-table}.
\arg{command-table} is a \term{command table designator}.

\cl{map-over-command-table-menu-items} does not descend into sub-menus.  If the
programmer requires this behavior, he should examine the type of the command
menu item to see if it is \cl{:menu}.

If \arg{inherited} is \term{false}, this applies \arg{function} only to those
menu items present in \arg{command-table}, that is, it does not map over any
inherited menu items. If \arg{inherited} is \term{true}, then the inherited
menus are traversed in the same order as for
\cl{do-command-table-inheritance}.


\Defun {find-menu-item} {menu-name command-table \key (errorp t)}

Given a menu name and a command table, returns two values, the command menu
item and the command table in which it was found.  \arg{command-table} is a
\term{command table designator}.

\ReadOnly

If there is no command menu item corresponding to \arg{menu-name} present in
\arg{command-table} and \arg{errorp} is \term{true}, then the
\cl{command-not-accessible} error will be signalled.  Note that the character
case of \arg{string} is ignored when searching the command table's menu.


\Defun {command-menu-item-type} {menu-item}

Returns the type of the command menu item \arg{menu-item}, for example,
\cl{:menu} or \cl{:command}.  If \arg{menu-item} is not a command menu item, the
result is unspecified.

\Defun {command-menu-item-value} {menu-item}

Returns the value of the command menu item \arg{menu-item}.  For example, if the
type of \arg{menu-item} is \cl{:command}, this will return a command or a
command name.  If \arg{menu-item} is not a command menu item, the result is
unspecified.

\Defun {command-menu-item-options} {menu-item}

Returns a list of the options for the command menu item \arg{menu-item}.  If
\arg{menu-item} is not a command menu item, the result is unspecified.


\Defgeneric {display-command-table-menu} {command-table stream
                                          \key max-width max-height n-rows n-columns
                                               x-spacing y-spacing initial-spacing row-wise
                                               (cell-align-x \cl{:left}) (cell-align-y \cl{:top})
                                               (move-cursor \cl{t})}

Displays \arg{command-table}'s menu on \arg{stream}.  Implementations may choose
to use \cl{formatting-item-list} or may display the command table's menu in a
platform dependent manner, such as using the menu bar on a Macintosh.
\arg{command-table} is a \term{command table designator}.

\arg{max-width}, \arg{max-height}, \arg{n-rows}, \arg{n-columns},
\arg{x-spacing}, \arg{y-spacing}, \arg{row-wise}, \arg{initial-spacing},
\arg{cell-align-x}, \arg{cell-align-y}, and \arg{move-cursor} are as for
\cl{formatting-item-list}.

\Defun {menu-choose-command-from-command-table} {command-table
                                                 \key associated-window default-style label
                                                      cache unique-id id-test
                                                      cache-value cache-test}

Invokes a window system specific routine that displays a menu of commands from
\arg{command-table}'s menu, and allows the user to choose one of the commands.
\arg{command-table} is a \term{command table designator}.  The returned value is
a command object.  This may invoke itself recursively when there are sub-menus.

\arg{associated-window}, \arg{default-style}, \arg{label}, \arg{cache},
\arg{unique-id}, \arg{id-test}, \arg{cache-value}, and \arg{cache-test} are as
for \cl{menu-choose}.

\issue {SWM} {Should this be generic on application frames?}


\section {Keystroke Accelerators}

Each command table may have a mapping from keystroke accelerator gesture names
to command menu items.  When a user types a key on the keyboard that corresponds
to the gesture for keystroke accelerator, the corresponding command menu item
will be invoked.  Note that command menu items are shared among the command
table's menu and the accelerator table.  There are several reasons for this.
One is that it is common to have menus display the keystroke associated with a
particular item, if there is one.

Note that, despite the fact the keystroke accelerators are specified using
keyboard gesture names rather than characters, the conventions for typed
characters vary widely from one platform to another.  Therefore the programmer
must be careful in choosing keystroke accelerators.  Some sort of per-platform
conditionalization is to be expected.


\Defun {add-keystroke-to-command-table} {command-table gesture type value
                                         \key documentation (errorp t)}

Adds a command menu item to \arg{command-table}'s keystroke accelerator table.
\arg{gesture} is a keyboard gesture name to be used as the accelerator.
\arg{type} and \arg{value} are as in \cl{add-menu-item-to-command-table}, except
that \arg{type} must be either \cl{:command}, \cl{:function} or \cl{:menu}.
\arg{command-table} is a \term{command table designator}.

\issue {SWM} {Should we allow \arg{gesture} to be a gesture specification as
well as just a gesture name?  It simplifies its use by avoiding a profusion of
defined gesture names, but we may want to encourage the use of gesture names.}

\arg{documentation} is a documentation string, which can be used as
documentation for the keystroke accelerator.

If the command menu item associated with \arg{gesture} is already present in the
command table's accelerator table and \arg{errorp} is \term{true}, then the
\cl{command-already-present} error will be signalled.  When the item is already
present in the command table's accelerator table and \arg{errorp} is
\term{false}, the old item will first be removed.


\Defun {remove-keystroke-from-command-table} {command-table gesture \key (errorp t)}

Removes the command menu item named by keyboard gesture name \arg{gesture} from
\arg{command-table}'s accelerator table.  \arg{command-table} is a \term{command
table designator}.

If the command menu item associated with \arg{gesture} is not present in the
command table's menu and \arg{errorp} is \term{true}, then the
\cl{command-not-present} error will be signalled.


\Defun {map-over-command-table-keystrokes} {function command-table \key (inherited t)}

Applies \arg{function} to all of the keystroke accelerators in
\arg{command-table}'s accelerator table.  \arg{function} must be a function of
three arguments, the menu name (which will be \cl{nil} if there is none), the
keystroke accelerator, and the command menu item; it has dynamic extent.
\arg{command-table} is a \term{command table designator}.

\cl{map-over-command-table-keystrokes} does not descend into sub-menus.  If the
programmer requires this behavior, he should examine the type of the command
menu item to see if it is \cl{:menu}.

If \arg{inherited} is \term{false}, this applies \arg{function} only to those
keystroke accelerators present in \arg{command-table}, that is, it does not
map over any inherited menu items. If \arg{inherited} is \term{true}, then the
inherited menus are traversed in the same order as for
\cl{do-command-table-inheritance}.


\Defun {find-keystroke-item} {gesture command-table \key test (errorp t)}

Given a keyboard gesture \arg{gesture} and a command table, returns two
values, the command menu item associated with the gesture and the command
table in which it was found.

\ReadOnly

\arg{test} is the test used to compare the supplied gesture to the gesture name
in the command table.  The supplied gesture will generally be an event object,
so the default for \arg{test} is \cl{event-matches-gesture-name-p}.

If the keystroke accelerator is not present in \arg{command-table} and
\arg{errorp} is \term{true}, then the \cl{command-not-accessible} error will
be signalled.  \arg{command-table} is a \term{command table designator}.

\Defun {lookup-keystroke-item} {gesture command-table \key test}

Given a keyboard gesture \arg{gesture} and a command table, returns two values,
the command menu item associated with the gesture and the command table in which
it was found.  Note that \arg{gesture} may be either a keyboard gesture name of
a gesture object, and is handled in the same way as in \cl{find-keystroke-item}.

\ReadOnly

Unlike \cl{find-keystroke-item}, this follows the sub-menu chains that can be
created with \cl{add-menu-item-to-command-table}. If a given sub-menu has an
associated keystroke that is not \arg{gesture}, the function does not look in
the keystroke accelerators table associated with the sub-menu.

If the keystroke accelerator cannot be found in the command table or its
menus, \cl{lookup-keystroke-item} will return \cl{nil}. \arg{command-table} is
a \term{command table designator}.

\arg{test} is the test used to compare the supplied gesture to the gesture name
in the command table.  The supplied gesture will generally be an event object,
so the default for \arg{test} is \cl{event-matches-gesture-name-p}.

\Defun {lookup-keystroke-command-item} {gesture command-table \key test numeric-arg}

Given a keyboard gesture \arg{gesture} and a command table, returns the command
associated with the keystroke, or \arg{gesture} if no command is found.  Note
that \arg{gesture} may be either a keyboard gesture name of a gesture object,
and is handled in the same way as in \cl{find-keystroke-item}.
\ReadOnly

This is like \cl{find-keystroke-item}, except that only keystrokes that map to
an enabled application command will be matched.  \arg{command-table} is a
\term{command table designator}.

\arg{test} is the test used to compare the supplied gesture to the gesture name
in the command table.  The supplied gesture will generally be an event object,
so the default for \arg{test} is \cl{event-matches-gesture-name-p}.

\arg{numeric-arg} (which defaults to 1) is substituted into the resulting
command for any occurrence of \cl{*numeric-argument-marker*} in the command.
This is intended to allow programmers to define keystroke accelerators that take
simple numeric arguments, which will be passed on by the input editor.

\issue {SWM} {Do the above three functions need to have their hands on the port?
If \cl{event-matches-gesture-name-p} needs the port, then the answer is yes.
Otherwise, if gesture names are ``global'' across all ports, then these don't
need the port.}

\Defun {substitute-numeric-argument-marker} {command numeric-arg}

Given a command object \arg{command}, this substitutes the value of
\arg{numeric-arg} for all occurrences of the value of
\cl{*numeric-argument-marker*} in the command, and returns a command object
with those substitutions.


\section {Presentation Translator Utilities}

These are some utilities for maintain presentation translators in
command tables.  Presentation translators are discussed in more detail
in Chapter~\ref{presentation-types}.


\Defun {add-presentation-translator-to-command-table} {command-table translator
                                                       \key (errorp t)}

Adds \arg{translator} to \arg{command-table}.  \arg{translator} must
have been previously defined with \cl{define-presentation-translator}
or \cl{define-presentation-to-command-translator}.
\arg{command-table} is a \term{command table designator}.

If a translator having the same name as \arg{translator} is already
present in \arg{command-table} and \arg{errorp} is \term{true}, then
the \cl{command-already-present} error will be signalled.  When such a
translator is already present and \arg{errorp} is \term{false}, the
old translator will first be removed.


\Defun {remove-presentation-translator-from-command-table} {command-table translator-name
                                                            \key (errorp t)}

Removes the translator named by \arg{translator-name} from \arg{command-table}.
\arg{command-table} is a \term{command table designator}.

If the translator is not present in the command table and \arg{errorp} is
\term{true}, then the \cl{command-not-present} error will be signalled.


\Defun {map-over-command-table-translators} {function command-table \key (inherited t)}

Applies \arg{function} to all of the translators accessible in
\arg{command-table}.  \arg{function} must be a function of one argument, the
translator; it has dynamic extent.  \arg{command-table} is a \term{command table
designator}.

If \arg{inherited} is \term{false}, this applies \arg{function} only to
those translators present in \arg{command-table}, that is, it does
not map over any inherited command tables.  If \arg{inherited} is
\term{true}, then the inherited command tables are traversed in the same
order as for \cl{do-command-table-inheritance}.


\Defun {find-presentation-translator} {translator-name command-table \key (errorp t)}

Given a translator name and a command table, returns two values, the
presentation translator and the command table in which it was found.  If the
translator is not present in \arg{command-table} and \arg{errorp} is
\term{true}, then the \cl{command-not-accessible} error will be signalled.
\arg{command-table} is a \term{command table designator}.


\section {The Command Processor}

Once a set of commands has been defined, CLIM provides a variety of means to
read a command.  These are all mediated by the Command Processor.


\Defun {read-command} {command-table
                       \key (stream *standard-input*)
                            command-parser command-unparser partial-command-parser
                            use-keystrokes}

\cl{read-command} is the standard interface used to read a command line.
\arg{stream} is an extended input stream, and \arg{command-table} is a
\term{command table designator}.

\arg{command-parser} must be a function of two arguments, a command table and a
stream.  It reads a command from the user and returns a command object, or
\cl{nil} if an empty command line was read.  The default value for
\arg{command-parser} is the value of \cl{*command-parser*}.

\arg{command-unparser} must be a function of three arguments, a command table, a
stream, and a command to ``unparse''.  It prints a textual description of the
command its supplied arguments onto the stream.  The default value for
\arg{command-unparser} is the value of \cl{*command-unparser*}.

\arg{partial-command-parser} must be a function of four arguments, a command
table, a stream, a partial command, and a start position.  The partial command
is a command object with the value of \cl{*unsupplied-argument-marker*} in place
of any argument that needs to be filled in.  The function reads the remaining,
unsupplied arguments in any way it sees fit (for example, via an
\cl{accepting-values} dialog), and returns a command object.  The start position
is the original input-editor scan position of the stream, when the stream is an
interactive stream.  The default value for \arg{partial-command-parser} is the
value of \cl{*partial-command-parser*}.

\arg{command-parser}, \arg{command-unparser}, and \arg{partial-command-parser}
have dynamic extent.

When \arg{use-keystrokes} is \term{true}, the command reader will also process
keystroke accelerators.  (Implementations will typically use
\cl{with-command-table-keystrokes} and \cl{read-command-using-keystrokes} to
implement the case when \arg{use-keystrokes} is \term{true}.)

Input editing, while conceptually an independent facility, fits into the command
processor via its use of \cl{accept}.  That is, \cl{read-command} must be
implemented by calling \cl{accept} to read command objects, and \cl{accept}
itself makes use of the input editing facilities.


\Defmacro {with-command-table-keystrokes} {(keystroke-var command-table) \body body}

Binds \arg{keystroke-var} to a sequence that contains all of the keystroke
accelerators in \arg{command-table}'s menu, and then executes \arg{body} in that
context.  \arg{command-table} is a \term{command table designator}.  \arg{body}
may have zero or more declarations as its first forms.

\Defun {read-command-using-keystrokes} {command-table keystrokes
                                        \key (stream *standard-input*)
                                             command-parser command-unparser
                                             partial-command-parser}

Reads a command from the user via command lines, the pointer, or a single
keystroke, and returns either a command object, or a keyboard gesture object if
the user typed a keystroke that is in \arg{keystrokes} but does not have a
command associated with it in \arg{command-table}.

\arg{keystrokes} is a sequence of keyboard gesture names that are the keystroke
accelerators.

\arg{command-table}, \arg{stream}, \arg{command-parser}, \arg{command-unparser},
and \arg{partial-command-parser} are as for \cl{read-command}.


\Defun {command-line-command-parser} {command-table stream}

The default command-line parser.  It reads a command name and the command's
arguments as a command line from \arg{stream} (with completion as much as is
possible), and returns a command object.  \arg{command-table} is a \term{command
table designator} that specifies the command table to use; the commands are read
via the textual command-line name.

\Defun {command-line-command-unparser} {command-table stream command}

The default command-line unparser.  It prints the command \arg{command} as a
command name and its arguments as a command line on \arg{stream}.
\arg{command-table} is a \term{command table designator} that specifies the
command table to use; the commands are displayed using the textual command-line
name.

\Defun {command-line-read-remaining-arguments-for-partial-command}
       {command-table stream partial-command start-position}

The default partial command-line parser.  If the remaining arguments are at the
end of the command line, it reads them as a command line, otherwise it
constructs a dialog using \cl{accepting-values} and reads the remaining
arguments from the dialog.  \arg{command-table} is a \term{command table
designator}.

\Defun {menu-command-parser} {command-table stream}

The default menu-driven command parser.  It uses only pointer clicks to
construct a command.  It relies on presentations of all arguments being visible.
\arg{command-table} and \arg{stream} are as for \cl{command-line-parser}.

There is no menu-driven command unparser, since it makes no sense to unparse a
completely menu-driven command.

\Defun {menu-read-remaining-arguments-for-partial-command}
       {command-table stream partial-command start-position}

The default menu-driven partial command parser.  It uses only pointer clicks to
fill in the command.  Again, it relies on presentations of all arguments being
visible.  \arg{command-table} is a \term{command table designator}.


\Defvar {*command-parser*}

Contains the currently active command parsing function.  The default value is
the function \cl{command-line-command-parser}, which is the default command-line
parser.

\Defvar {*command-unparser*}

Contains the currently active command unparsing function.  The default value is
the function \cl{command-line-command-unparser}, which is the default
command-line unparser.

\Defvar {*partial-command-parser*}

Contains the currently active partial command parsing function.  The default value
is the function \cl{command-line-read-remaining-arguments-for-partial-command}.

\Defvar {*unsupplied-argument-marker*}

The value of \cl{*unsupplied-argument-marker*} is an object that can be uniquely
identified as standing for an unsupplied argument in a command object.

\Defvar {*numeric-argument-marker*}

The value of \cl{*numeric-argument-marker*} is an object that can be uniquely
identified as standing for a numeric argument in a command object.

\Defvar {*command-name-delimiters*}

This is a list of the characters that separate the command name from the command
arguments in a command line.  The standard set of command name delimiters must
include \verb+#\Space+.

\Defvar {*command-argument-delimiters*}

This is a list of the characters that separate the command arguments from each
other in a command line.  The standard set of command argument delimiters must
include \verb+#\Space+.


\subsection {Command Presentation Types}

\Defptype {command} {\key command-table}

The presentation type used to represent a command and its arguments; the command
must be accessible in \arg{command-table} and enabled in
\cl{*application-frame*}.  \arg{command-table} is a \term{command table
designator}.  If \arg{command-table} is not supplied, it defaults to the command
table for the current application frame, \cl{(frame-command-table
*application-frame*)}.

The object returned by the \cl{accept} presentation method for \cl{command}
must be a command object, that is, a cons of the command name and the list of
the command's arguments.

The \cl{accept} presentation method for the \cl{command} type must call the
command parser stored in \cl{*command-parser*} to read the command.  The parser
will recursively call \cl{accept} to read a \cl{command-name} and all of the
command's arguments.  The parsers themselves must be implemented by accepting
objects whose presentation type is \cl{command}.

If the command parser returns a partial command, the \cl{accept} presentation
method for the \cl{command} type must call the partial command parser stored in
\cl{*partial-command-parser*}.

The \cl{present} presentation method for the \cl{command} type must call the
command unparser stored in \cl{*command-unparser*}.

If a presentation history is maintained for the \cl{command} presentation type,
it should be maintained separately for each instance of an application frame.

\Defptype {command-name} {\key command-table}

The presentation type used to represent the name of a command that is both
accessible in the command table \arg{command-table} and enabled in
\cl{*application-frame*}.  \arg{command-table} is a \term{command table
designator}.  If \arg{command-table} is not supplied, it defaults to the command
table for the current application frame, \cl{(frame-command-table
*application-frame*)}.

The textual representation of a \cl{command-name} object is the command-line
name of the command, while the internal representation is the command name.

\Defptype {command-or-form} {\key command-table}

The presentation type used to represent an object that is either a Lisp form, or
a command and its arguments.  The command must be accessible in
\arg{command-table} and enabled in \cl{*application-frame*}.  \arg{command-table}
is a \term{command table designator}.  If \arg{command-table} is not supplied, it
defaults to the command table for the current application frame,
\cl{(frame-command-table *application-frame*)}.

The \cl{accept} presentation method for this type reads a Lisp form, except that
if the first character in the user's input is one of the characters in
\cl{*command-dispatchers*} it will read a command.  The two returned values from
the \cl{accept} presentation method will be the command or form object and a
presentation type specifier that is either \cl{command} or \cl{form}.

If a presentation history is maintained for the \cl{command-or-form}
presentation type, it should be maintained separately for each instance of an
application frame.

\Defvar {*command-dispatchers*}

This is a list of the characters that indicates that CLIM reads a command when
it is accepting a \cl{command-or-form}.  The standard set of command argument
delimiters must include the colon character, \verb+#\:+.
